/*
 * Copyright 2013 floreysoft GmbH (www.floreysoft.net)
 *
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.floreysoft.gwt.drive.client.realtime;

/**
 * Creates a new collaborative string. Unlike regular JavaScript strings,
 * collaborative strings are mutable.
 * 
 * Changes to the string will automatically be synced with the server and other
 * collaborators. To listen for changes, add EventListeners for the following
 * event types:
 * 
 * gapi.drive.realtime.EventType.TEXT_INSERTED
 * gapi.drive.realtime.EventType.TEXT_DELETED
 * 
 * This class should not be instantiated directly. To create a new collaborative
 * string, use gapi.drive.realtime.Model.prototype.createString
 * 
 */
public final class CollaborativeString extends EventTarget {

	protected CollaborativeString() {
	}

	public native int lenght() /*-{
		return this.length;
	}-*/;

	/**
	 * Sets the contents of this collaborative string. Note that this method
	 * performs a text diff between the current string contents and the new
	 * contents so that the string will be modified using the minimum number of
	 * text inserts and deletes possible to change the current contents to the
	 * newly-specified contents.
	 * 
	 * @param text
	 *            The new value of the string.
	 */
	public native void setText(String text)/*-{
		this.setText(text);
	}-*/;

	/**
	 * Gets a string representation of the collaborative string.
	 * 
	 * @return A string representation of the collaborative string.
	 */
	public native String getText() /*-{
		return this.getText();
	}-*/;

	/**
	 * Appends a string to the end of this one.
	 * 
	 * @param text
	 *            The new text to append
	 */
	public native void append(String text)/*-{
		this.append(text);
	}-*/;

	/**
	 * Inserts a string into the collaborative string at a specific index.
	 * 
	 * @param index
	 *            index to insert at
	 * @param text
	 *            the new text to insert
	 */
	public native void insertString(int index, String text)/*-{
		this.insertString(index, text);
	}-*/;

	/**
	 * Deletes the text between startIndex (inclusive) and endIndex (exclusive).
	 * 
	 * @param startIndex
	 *            The start index of the range to delete (inclusive).
	 * @param endIndex
	 *            The end index of the range to delete (exclusive).
	 */
	public native void removeRange(int startIndex, int endIndex)/*-{
		this.removeRange(startIndex, endIndex);
	}-*/;

	/**
	 * Creates an IndexReference at the given {@code index}. If
	 * {@code canBeDeleted} is set, then a delete over the index will delete the
	 * reference. Otherwise the reference will shift to the beginning of the
	 * deleted range.
	 * 
	 * @param index
	 *            The index of the reference.
	 * @param canBeDeleted
	 *            Whether this index is deleted when there is a delete of a
	 *            range covering this index.
	 * @return {@link IndexReference} The newly registered reference.
	 */
	public native IndexReference registerReference(int index,
			boolean canBeDeleted)/*-{
		return this.registerReference(index, canBeDeleted)
	}-*/;

}
